Magnum One/Magnum One (Mid-American Digital) (Disc Manufacturing).iso/d13/rio2.arc/RIO.DOC

Text File | 1991-03-19 | 17KB | 345 lines

RIO 2.0 (Released 3/91)

Beware: RIO can cause your system to hang (it's not common, but it can
happen), forcing you to reboot.  If you find a way to consistently hang the
program, please let the author know - it would help in eradicating the
bug(s)!

Purpose

    RIO-TSR (Rock Input/Output) is a memory-resident program (takes about
    80K) that logs all DOS disk I/O operations and other functions to a
    file for later study.  It can be useful in debugging software and
    network problems by showing what DOS calls are made along with their
    results, without the need to delve into a program's source code.

    RIO-TSR is a memory-resident (TSR) program that logs DOS I/O operations
    & functions to a text file for later study.  It's useful for debugging
    software and network problems by showing DOS calls & their results,
    without the need to delve into a program's source code.

    With RIO 2.0, there is now a non-TSR program, RIO, which lets you
    browse the log file and change the RIO-TSR's settings, for example to
    log only certain interrupts.  The new version also logs Novell Netware
    & direct disk I/O calls.

    RIO is geared towards programmers, but advanced non-programmers may
    find it of use as well.  For example, it's possible to detect problems
    in a program such as not closing a file without really understanding
    how interrupts work.  But the more you understand about DOS interrupts
    the more you'll get out of RIO's reports.

    RIO can be useful in "reverse-engineering" how a program accomplishes
    certain tasks, or in decoding a data file format by listing the number
    of bytes read/written during each DOS call (see the section on File
    Reads & Writes).

    RIO can also point out inefficiencies in a program, for example if the
    program checks a file size fifty times, when it could have checked it
    once, stored it in a variable, and not wasted time accessing hte disk
    repeatedly.


Loading the TSR

    To install, type

         RIO-TSR [filename]

    If you type just RIO-TSR, the log file defaults to C:\RIO. If the file
    already exists, you'll get the following prompt:

    C:>rio-tsr
    RIO-TSR 2.0 (3/91) - Rock I/O logger, (C) 1991 Rock

    File C:\RIO already exists; append, erase & overwrite, or
    cancel (a/e/c)?

    If you type A or E, the program will "go resident", operating in the
    background, and you'll be returned to the DOS prompt. If you type C,
    RIO-TSR will not go resident.

HotKeys

    Certain aspects of RIO can be controlled by pressing hot keys after it
    has gone resident. The following table lists the hot keys:

      LeftShift-RightShift-L  Toggle logging
      LeftShift-RightShift-C  Clear log file
      LeftShift-RightShift-U  Unload TSR

    When logging is off, no further I/O operations will be logged until it
    is turned on again.  If your system is slowed down with file accesses
    you're not interested in, you should turn logging off.  After logging
    is resumed, new operations are appended to the existing log file.


Command-line switches

    You can unload RIO-TSR or toggle logging by using running RIO-TSR
    with command-line switches.  Type "RIO-TSR /U" to unload the program,
    or "RIO-TSR /L" to toggle the logging on or off.


Running RIO

    RIO allows you to turn on or off logging of particular interrupts.
    After you load RIO-TSR, run RIO, and it will provide a full-screen
    program with pulldown menus.  Commands are listed at the bottom of
    the screen, and the program will hopefully be self-explanatory.


Operation

    The log file created and repeatedly updated by RIO-TSR is a text file
    showing information about each DOS I/O call.  It lists the call number,
    its operation, input and output from the call, the time, and/or the
    date, according to the settings, which are adjustable from the program
    RIO.EXE.  The following are taken from a sample log file:

    ┌──────────────────┬─────────────────────────────────┬──────────┐
    │Operation         │Information sent -> returned     │Time      │
    └──────────────────┴─────────────────────────────────┴──────────┘
    Get Break Flag      -> Off                           16:16:21.16
    Set Break Flag      Off                              16:16:21.16
    Open (Read-only)    C:\COLORS.RIR -> Handle 5        16:16:21.55
    Close File          Handle 5                         16:16:21.55

    The -> symbol in the "Information sent -> returned" column means that
    the information was returned from teh call.  A "get" call typically
    just returns information, while a "set" call typically just sends
    information to the interrupt procedure.  In the case of the "Open
    (Read-only)" call, a file name is sent to the interrupt, and a handle
    number is returned.  Each opened file is assigned a handle number, and
    subsequent calls relating to the file will use that handle number (as
    in the next call, Close File).  The maximum handle number can be set by
    the "FILES=" command in a config.sys file, for example "FILES=20" means
    up to 20 handles may be assigned at the same time.

    Note that RIO-TSR does not log its own I/O operations.  RIO, the
    non-TSR program, will cause some I/O operations to be logged.

    RIO-TSR will put a special message in the log file if it is unable to
    log all the information.  RIO-TSR uses a memory buffer to hold log
    information until it is safe to write it to disk. If the buffer
    overflows before it can be logged, the log file will contain a line
    indicating how many lines were lost.

    RIO-TSR will also put a line in if the same interrupt is called
    repeatedly, for example if "Find Next File" is called 100 times, it
    will list the first three calls, then say "call repeated 97 more
    times."  The number of calls to list before saying it was repeated is
    adjustable from RIO.

    For the technically minded, Appendices A & B list the interrupt $21
    functions that can be logged.


File Reads & Writes

    File Read/Write calls (Interrupt $21, finctions $3F and $40) are by
    default not logged, because some programs call these functions a *lot*,
    and the results generally aren't that interesting.  However, you can
    have these functions logged by turning them on from RIO's "Interrupts"
    menu.

    Logging these interrupts can be very useful in trying to decode an
    unknown file format that a program uses.  If the program writes each
    field with a separate call, you can see exactly how many bytes it
    writes per call.  As a simple example, if a database program keeps
    writing 4 bytes, 1 byte, 2 bytes, and keeps repeating this sequence,
    it's indicative that it's writing fields of those lengths (perhaps a
    date, followed by a boolean value, followed by an integer).  File
    headers, the initial area of data files, are often written and read one
    variable at a time.


Failed DOS calls

    Unsuccessful or "failed" DOS calls are usually listed with the the
    error code they return.  Note that a DOS call returning an error does
    *not* indicate a program bug.  For example, to determine if a file
    exists, many programs try opening the file, and if it fails, it knows
    it doesn't exist.  As long as the program you're running realizes when
    DOS reports an error, rather than trying to write to a file it never
    successfully opened, then the program should work fine.

    RIO plays sound effects when it issues functions called by hotkeys.
    When logging is toggled, "on" is denoted by a rising scale of tones,
    "off" by a falling scale.  Clearing the file results in a muddy
    warbling sound, and successfully unloading RIO-TSR results in the first
    few notes of Taps being played.

File Attributes

    Get Attr, Set Attr, and some other file-related calls are followed by
    attribute codes given in brackets, for example "[RHSVDA]".  A sample
    line from a log file would be:

    Find First File     [RHS DA] C:\*.* -> .

    This means the Find First File is looking for a file with any
    attributes other than the Volume attribute, and the "." directory entry
    was returned.

    The letters within brackets stand for the following file attributes:

            R - Read only   H - Hidden     S - System
            V - Volume      D - Directory  A - Archive


New Features

    The logging of each function is configurable, so the logging of
    particular Int $21 functions can be turned on or off.  Also, features
    such as time/date stamping, or logging of interrupt function numbers,
    can be turned on or off.

    These options are selectable from a separate non-TSR program which
    communicates with RIO-TSR, so that this larger program won't hog your
    system RAM while you're running RIO-TSR.

    Also, this version of RIO-TSR can be unloaded.


Credits

    RIO-TSR is based on the public domain IOLOG 1.0 (12/88) by Kim Kokkonen
    of TurboPower Software, and uses TurboPower's (excellent!) Object
    Professional toolkit for Turbo Pascal. Mr. Kokkonen credits Don
    Pearsall for IOLOG's inspiration. IOLOG provides much less information
    (it logs around a dozen interrupts), and is not as configurable, but it
    is public domain, and the source code is included with Object
    Professional. The user interface for RIO also makes use of Object
    Professional's menu and window routines.  If you're into Turbo Pascal,
    their software and support comes highly recommended.


Contacting the Author

    Any suggestions or ideas are welcome; e-mail Rob Argy on CompuServe,
    CIS [71270,146], or call Rock Systems at [phone].  See the file
    ORDERING.DOC or ORDER.FRM for information on registering your copy of
    RIO.

Example output - log file, default options

┌───┬───┬───────────────────┬─────────────────────────────────────────────┐
│In#│Fn#│Operation          │Information sent -> returned                 │
└───┴───┴───────────────────┴─────────────────────────────────────────────┘
 $21 $4E Find First File     [RHS   ] D:\B\RIR.EXE -> RIR.EXE
 $21 $47 Get Current Dir     Drive 4 ->
 $21 $29 Parse File Name      /W
 $21 $29 Parse File Name
 $21 $35 Get Intr Vector     Int $00 -> $19B3:0898
 $21 $35 Get Intr Vector     Int $02 -> $18E5:0016
 $21 $35 Get Intr Vector     Int $1B -> $0070:07F5

                    < call repeated 15 more times >

 $21 $25 Set Intr Vector     Int $00 to $432C:00CE
 $21 $30 Get DOS Version     -> 4.0 (OEM #255)
 $21 $38 Get Country Data    -> United States
 $21 $33 Get Break Flag      -> Off
 $21 $33 Set Break Flag      Off
 $21 $25 Set Intr Vector     Int $1B to $4176:0731
 $21 $3D Open (Read-only)    C:\COLORS.RIR -> Handle 5
 $21 $42 Seek Relative       Handle 5, 0 bytes -> (get pos:) at byte 0
 $21 $42 Seek From End       Handle 5, 0 bytes -> (get size:) 395 bytes
 $21 $42 Seek From Start     Handle 5, 0 bytes -> to byte 0
 $21 $3E Close File          Handle 5
 $21 $2C Get System Time     -> 00:15:30.38
 $21 $19 Get Current Disk    -> Physical drive C:


Example output - log file, time-stamp turned on

┌──────────────────┬───────────────────────────────────────────┬──────────┐
│Operation         │Information sent -> returned               │Time      │
└──────────────────┴───────────────────────────────────────────┴──────────┘

Get DOS Version     -> 4.0 (OEM #255)                          16:16:21.16
Get Country Data    -> United States                           16:16:21.16
Get Break Flag      -> Off                                     16:16:21.16
Set Break Flag      Off                                        16:16:21.16
Set Intr Vector     Int $1B to $5C65:0731                      16:16:21.16
Open (Read-only)    C:\COLORS.RIR -> Handle 5                  16:16:21.55
Seek Relative       Handle 5, 0 bytes -> (get pos:) at byte 0  16:16:21.55
Seek From End       Handle 5, 0 bytes -> (get size:) 395 bytes 16:16:21.55
Seek From Start     Handle 5, 0 bytes -> to byte 0             16:16:21.55
Close File          Handle 5                                   16:16:21.55
Get System Time     -> 16:16:21.60                             16:16:21.60
Get Current Disk    -> Physical drive C:                       16:16:21.60
Findfile            [RH  D ] T.???                             16:16:21.65
Findfile            [RH  D ] D:\B\T.???                        16:16:21.65

Appendix A - Interrupt $21 DOS functions logged

Int $21 DOS functions

$01 Read, Echo Keyboard  $24 FCB Set Rel. Record  $48 Allocate Mem Block
$02 Display Character    $25 Set Intr Vector      $49 Release Mem Block
$03 Auxiliary Input      $26 Create New Prog Seg  $4A Resize Memory Block
$04 Auxiliary Output     $27 FCB Rndm Block Read  $4D Get Return Code
$05 Print Character      $28 FCB Rndm Blck Write  $4E Find First File
$06 Direct Console I/O   $29 Parse File Name      $4F Find Next File
$07 Direct Console Inp.  $2A Get System Date      $50 Set PSP Segment
$08 Read Kybrd w/o Echo  $2B Set System Date      $51 Get PSP Seg (buggy)
$09 Display String       $2C Get System Time      $52 Get DOS Variables
$0A Buffered Kybd Input  $2D Set System Time      $53 Translate BPB
$0B Check Kybrd Status   $2E (Re)set Verify Flag  $54 Get Verify Flag
$0C Flush & read kybrd   $2F Get Disk X-fer Addr  $55 Duplicate PSP Block
$0D Reset Disk           $30 Get DOS Version      $56 Rename File
$0E Select Disk          $32 Get Disk's DPB Ptr   $57 Get/Set File Date
$0F FCB Open File        $33 Break Flag/Boot Drv  $58 Get/Set Alloc Strat
$10 FCB Close File       $34 Get DOS Busy Flag    $59 Get Ext Error Info
$11 FCB Find First       $35 Get Intr Vector      $5A Create Temp File
$12 FCB Find Next        $36 Get Free Diskspace   $5B Create New File
$13 FCB Delete File      $37 Get/Set Switch Char  $5C Lock/Unlock File
$14 FCB Seq. Read        $38 Get/Set Country      $5D Internal DOS Functn
$15 FCB Seq. Write       $39 Create Directory     $5E Mach Name/Prn Setup
$16 FCB Create File      $3A Remove Directory     $5F Assignment Entry
$17 FCB Rename File      $3B Change Directory     $60 Qualify Path String
$18 Reservd DOS Fnc $18  $3C Create File          $61 Reservd DOS Fnc $61
$19 Get Current Disk     $3D Open File            $62 Get PSP Address
$1A Set Disk X-fer Addr  $3E Close File           $63 Get DBCS,G/Set Cons
$1B Get Def. Drive Data  $3F Read File            $64 Reservd DOS Fnc $64
$1C Get Drive Data       $40 Write File           $65 Get Ext Country Inf
$1D Reservd DOS Fnc $1D  $41 Delete File          $66 Get/Set Code Page
$1E Reservd DOS Fnc $1E  $42 Seek File            $67 Set Handle Count
$1F Get Def Param Block  $43 Get/Set Attributes   $68 Commit File
$20 Reservd DOS Fnc $20  $44 IOC (I/O Control)    $69 Reservd DOS Fnc $69
$21 FCB Random Read      $45 Duplicate Handle     $6A Reservd DOS Fnc $6A
$22 FCB Random Write     $46 Force Dup Handle     $6B Reservd DOS Fnc $6B
$23 FCB Get File Size    $47 Get Current Dir      $6C Extended File Open

Appendix B - Interrupt $21 Novell Netware functions

Int $21 Novell Netware FCB functions

$BF NW FCB LOG Record    $CC NW FCB Release File  $E6 NW FCB Copy File
$C0 NW FCB Release Rcrd  $CE NW FCB Clear File    $E8 NW FCB St Reopn Mde
$C1 NW FCB Clear Record  $E4 NW FCB Set Attribs
$CA NW FCB Log Prs File  $E5 NW FCB Set FileSize


Int $21 Novell Netware other functions

$B6 NW Ext File Attribs  $CF NW Clear File Set    $E1 NW Broadcast Msgs
$B8 NWAdv Print Jobs     $D0 NW LOG Record        $E2 NW Directory Fnctns
$BB NW Set EOJob Status  $D1 NW LOCK Record Set   $E3 NW Connection Ctrl
$BC NW LOG Phys Record   $D2 NW Release Record    $E7 NW G/Set Srvr Tm&Dt
$BD NW Release Phys Rec  $D3 NW Release Recd Set  $E9 NW Get Base Status
$BE NW Clear Phys Recrd  $D4 NW Clear Record      $EA NW Get Shell Versn.
$C2 NW Lock Phys Rc Set  $D5 NW Clear Recrd Set   $EB NW Log File
$C3 NW Rels Phys Rc Set  $D6 NW End Of Job        $EC NW Release File
$C4 NW Clr Phys Rec Set  $D7 NW System Logout     $ED NW Clear File
$C5 NW Semaphores        $DA NW Get Volume Stats  $EE NW Get Phys Station
$C6 NW G/Set Lock Mode   $DB NW Get Local Drives  $EF NWAdv Get Drive Inf
$C7 NW TTS               $DC NW Get Station Num.  $F0 NWAdv Connection ID
$C8 NW Begin File Lock   $DD NW Set Error Mode    $F1 NWAdv Srvr Connectn
$C9 NW End File Locking  $DE NW Set Brodcst Mode  $F2 NW Unknown Function
$CB NW LOCK File Set     $DF NW Capture           $F3 NWAdv Srvr FileCopy
$CD NW Release File Set  $E0 NW Print Spooling